Working with Web.config (App.config) in .NET Framework

TLDR

• Use Build Configurations combined with Web.config Transform to automate the generation of environment-specific configuration files, preventing manual modification errors.
• Non-Web projects do not support Config Transform by default; you must install the SlowCheetah extension or NuGet package.
• Use the configSource or file attribute to extract shared settings (such as connection strings) into independent files for use across multiple projects.
• Use <location inheritInChildApplications="false"> to break the inheritance of the parent site's Web.config in child sites, preventing configuration conflicts.
• In Entity Framework Database First mode, it is not recommended to use external references or <location> tags for connection strings, as this will prevent the design-time UI from reading the configuration.

Publishing Different Configuration Files Based on Build Configurations

Configuration file content often differs between development, testing, and production environments. By combining Build Configurations (Debug/Release) with the Web.config Transform mechanism, you can automatically transform configuration values during publishing.

Web.config Transform for Web Projects

When a Web.{ConfigurationName}.config file is missing for a specific configuration in your project, you can right-click Web.config and select "Add Config Transform".

• Replacement Mechanism: Use xdt:Transform to define the action and xdt:Locator to define the target.
• Common Transformation Examples:

  <!-- Replace the entire node -->
  <connectionStrings xdt:Transform="Replace">
    <add name="Default" connectionString="..." />
  </connectionStrings>
  
  <!-- Match by attribute and replace a single attribute -->
  <add key="MyKey" value="NewValue" 
       xdt:Locator="Match(key)" xdt:Transform="SetAttributes" />
  
  <!-- Remove an attribute -->
  <compilation xdt:Transform="RemoveAttributes(debug)" />

App.config Transform for Non-Web Projects

Non-Web projects do not support this feature natively. You must handle it as follows:

• Install Package: Install the Visual Studio extension "SlowCheetah" or the NuGet package Microsoft.VisualStudio.SlowCheetah.
• Build Behavior: When a non-Web project is published, the build process triggers the Transform. It is recommended to clean the bin folder before building to ensure correct output.

TIP

The {Profile}.pubxml.user file generated when creating a publish profile is a user setting record and should not be included in version control.

Sharing Configuration Files Across Different Projects

When multiple projects (such as a Web API and a scheduler) share the same database settings, you can extract the settings into an independent file.

Setup Steps

1. Create an External Configuration File: Create a file such as Connection.config and configure xdt:Transform.
2. Project Reference: Add the file as a "Link" and configure the .csproj file:
   • Set <TransformOnBuild>true</TransformOnBuild>.
   • Set the external configuration file to <CopyToOutputDirectory>Always</CopyToOutputDirectory>.
   • Set the external configuration transform file to a <None /> node to prevent it from being copied during publishing.
3. Referencing Method:
   • configSource: Suitable for connectionStrings or smtp; does not allow merging with other settings.
   • file: Suitable for appSettings; allows merging with other settings.

WARNING

If using Entity Framework Database First, do not move connection strings to an external reference file, otherwise the Entity Framework design interface will be unable to read the connection strings.

Breaking Web.config Inheritance

When configuration conflicts occur in IIS child sites (e.g., different Framework versions), you can use the <location> tag in the parent site's Web.config to break inheritance:

<location path="." inheritInChildApplications="false">
  <system.web>
    <!-- Internal settings -->
  </system.web>
</location>

TIP

Do not wrap the <location> tag around Entity Framework connection strings, as this will cause the EF design interface to fail to read them.

Change Log

• 2022-11-10 Initial documentation created.